<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Profiling programs &mdash; The Logtalk Handbook v3.93.0-b01 documentation</title>
      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d75fae25" />
      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=19f00094" />
      <link rel="stylesheet" type="text/css" href="../_static/css/custom.css?v=396eccfe" />

  
  <!--[if lt IE 9]>
    <script src="../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
        <script src="../_static/jquery.js?v=5d32c60e"></script>
        <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
        <script src="../_static/documentation_options.js?v=c8100655"></script>
        <script src="../_static/doctools.js?v=9a2dae69"></script>
        <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../_static/js/theme.js"></script>
    <!-- begin favicon -->
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
    <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />
    <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />
    <link rel="manifest" href="/site.webmanifest" />
    <link rel="mask-icon" href="/safari-pinned-tab.svg" color="#5bbad5" />
    <meta name="msapplication-TileColor" content="#355b95" />
    <meta name="theme-color" content="#ffffff" />
    <!-- end favicon -->
    
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="FAQ" href="../faq/index.html" />
    <link rel="prev" title="A reflective class-based system" href="reflection.html" />
   
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >

          
          
          <a href="../index.html" class="icon icon-home">
            The Logtalk Handbook
              <img src="../_static/logtalk.gif" class="logo" alt="Logo"/>
          </a>
              <div class="version">
                3.93.0
              </div>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
    
              <p class="caption" role="heading"><span class="caption-text">Contents</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../userman/index.html">User Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="../refman/index.html">Reference Manual</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Tutorial</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="lists.html">List predicates</a></li>
<li class="toctree-l2"><a class="reference internal" href="attributes.html">Dynamic object attributes</a></li>
<li class="toctree-l2"><a class="reference internal" href="reflection.html">A reflective class-based system</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Profiling programs</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#messages-as-events">Messages as events</a></li>
<li class="toctree-l3"><a class="reference internal" href="#profilers-as-monitors">Profilers as monitors</a></li>
<li class="toctree-l3"><a class="reference internal" href="#summary">Summary</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../faq/index.html">FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devtools/index.html">Developer Tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../libraries/index.html">Libraries</a></li>
<li class="toctree-l1"><a class="reference internal" href="../ports/index.html">Ports</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributions/index.html">Contributions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
<li class="toctree-l1"><a class="reference internal" href="../bibliography.html">Bibliography</a></li>
<li class="toctree-l1"><a class="reference internal" href="../genindex.html">Index</a></li>
</ul>

    <p class="caption"><span class="caption-text">External Contents</span></p>
    <ul>
    <li class="toctree-l1"><a class="reference internal" href="../../apis/index.html">APIs</a></li>
    <li class="toctree-l1"><a class="reference internal" href="https://logtalk.org">Logtalk website</a></li>
    <li class="toctree-l1"><a class="reference internal" href="https://github.com/LogtalkDotOrg/logtalk3">GitHub repo</a></li>
    </ul>
  
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">The Logtalk Handbook</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="index.html">Tutorial</a></li>
      <li class="breadcrumb-item active">Profiling programs</li>
      <li class="wy-breadcrumbs-aside">
              <a href="https://github.com/LogtalkDotOrg/logtalk3/blob/master/docs/handbook/sources/tutorial/profiling.rst" class="fa fa-github"> Edit on GitHub</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="profiling-programs">
<h1>Profiling programs<a class="headerlink" href="#profiling-programs" title="Link to this heading"></a></h1>
<p>In this example, we will illustrate the use of:</p>
<ul class="simple">
<li><p>events</p></li>
<li><p>monitors</p></li>
</ul>
<p>by defining a simple profiler that prints the starting and ending time
for processing a message sent to an object.</p>
<section id="messages-as-events">
<span id="profiling-events"></span><h2>Messages as events<a class="headerlink" href="#messages-as-events" title="Link to this heading"></a></h2>
<p>In a pure object-oriented system, all computations start by sending
messages to objects. We can thus define an <em>event</em> as the sending of a
message to an object. An event can then be specified by the tuple
<code class="docutils literal notranslate"><span class="pre">(Object,</span> <span class="pre">Message,</span> <span class="pre">Sender)</span></code>. This definition can be refined by
interpreting the sending of a message and the return of the control to
the object that has sent the message as two distinct events. We call
these events respectively <code class="docutils literal notranslate"><span class="pre">before</span></code> and <code class="docutils literal notranslate"><span class="pre">after</span></code>. Therefore, we end up
by representing an event by the tuple
<code class="docutils literal notranslate"><span class="pre">(Event,</span> <span class="pre">Object,</span> <span class="pre">Message,</span> <span class="pre">Sender)</span></code>. For instance, if we send the
message:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- foo::bar(X).

X = 1
yes
</pre></div>
</div>
<p>the two corresponding events will be:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>(before, foo, bar(X), user)
(after, foo, bar(1), user)
</pre></div>
</div>
<p>Note that the second event is only generated if the message succeeds. If
the message as a goal has multiple solutions, then an <code class="docutils literal notranslate"><span class="pre">after</span></code> event
will be generated for each solution.</p>
<p>Events are automatically generated by the message-sending mechanisms for
each public message sent using the
<a class="reference internal" href="../refman/control/send_to_object_2.html#control-send-to-object-2"><span class="std std-ref">(::)/2</span></a> operator.</p>
</section>
<section id="profilers-as-monitors">
<span id="profiling-monitors"></span><h2>Profilers as monitors<a class="headerlink" href="#profilers-as-monitors" title="Link to this heading"></a></h2>
<p>A monitor is an object that reacts whenever a spied event occurs. The
monitor actions are defined by two event handlers:
<a class="reference internal" href="../refman/methods/before_3.html#methods-before-3"><span class="std std-ref">before/3</span></a> for <code class="docutils literal notranslate"><span class="pre">before</span></code> events
and <a class="reference internal" href="../refman/methods/after_3.html#methods-after-3"><span class="std std-ref">after/3</span></a> for <code class="docutils literal notranslate"><span class="pre">after</span></code>
events. These predicates are automatically called by the message-sending
mechanisms when an event registered for the monitor occurs. These event
handlers are declared as public predicates in the <code class="docutils literal notranslate"><span class="pre">monitoring</span></code>
built-in protocol.</p>
<p>In our example, we need a way to get the current time before and after
we process a message. We will assume that we have a <code class="docutils literal notranslate"><span class="pre">time</span></code> object
implementing a <code class="docutils literal notranslate"><span class="pre">cpu_time/1</span></code> predicate that returns the current CPU
time for the Prolog session:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(time).

<span class="p">    :- </span><span class="k">public</span>(cpu_time<span class="o">/</span><span class="m">1</span>).
<span class="p">    :- </span><span class="k">mode</span>(cpu_time(<span class="o">-</span>number), one).
    ...

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>Our profiler will be named <code class="docutils literal notranslate"><span class="pre">stop_watch</span></code>. It must define event handlers
for the <code class="docutils literal notranslate"><span class="pre">before</span></code> and <code class="docutils literal notranslate"><span class="pre">after</span></code> events that will print the event
description (object, message, and sender) and the current time:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(stop_watch,
    <span class="c">% event handler predicates protocol</span>
    <span class="k">implements</span>(monitoring)).

<span class="p">    :- </span><span class="k">uses</span>(time, [cpu_time<span class="o">/</span><span class="m">1</span>]).

    <span class="k">before</span>(<span class="nv">Object</span>, <span class="nv">Message</span>, <span class="nv">Sender</span>) <span class="o">:-</span>
        <span class="k">write</span>(<span class="nv">Object</span>), <span class="k">write</span>(<span class="s">&#39; &lt;-- &#39;</span>), <span class="k">writeq</span>(<span class="nv">Message</span>),
        <span class="k">write</span>(<span class="s">&#39; from &#39;</span>), <span class="k">write</span>(<span class="nv">Sender</span>), <span class="k">nl</span>, <span class="k">write</span>(<span class="s">&#39;STARTING at &#39;</span>),
        cpu_time(<span class="nv">Seconds</span>), <span class="k">write</span>(<span class="nv">Seconds</span>), <span class="k">write</span>(<span class="s">&#39; seconds&#39;</span>), <span class="k">nl</span>.

    <span class="k">after</span>(<span class="nv">Object</span>, <span class="nv">Message</span>, <span class="nv">Sender</span>) <span class="o">:-</span>
        <span class="k">write</span>(<span class="nv">Object</span>), <span class="k">write</span>(<span class="s">&#39; &lt;-- &#39;</span>), <span class="k">writeq</span>(<span class="nv">Message</span>),
        <span class="k">write</span>(<span class="s">&#39; from &#39;</span>), <span class="k">write</span>(<span class="nv">Sender</span>), <span class="k">nl</span>, <span class="k">write</span>(<span class="s">&#39;ENDING at &#39;</span>),
        cpu_time(<span class="nv">Seconds</span>), <span class="k">write</span>(<span class="nv">Seconds</span>), <span class="k">write</span>(<span class="s">&#39; seconds&#39;</span>), <span class="k">nl</span>.

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>After compiling and loading the <code class="docutils literal notranslate"><span class="pre">stop_watch</span></code> object (and the objects
that we want to profile), we can use the <a class="reference internal" href="../refman/predicates/define_events_5.html#predicates-define-events-5"><span class="std std-ref">define_events/5</span></a>
built-in predicate to set up our profiler. For example, to profile all
messages that are sent to the object <code class="docutils literal notranslate"><span class="pre">foo</span></code>, we need to call the goal:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- define_events(_, foo, _, _, stop_watch).

yes
</pre></div>
</div>
<p>This call will register <code class="docutils literal notranslate"><span class="pre">stop_watch</span></code> as a monitor to all messages sent
to object <code class="docutils literal notranslate"><span class="pre">foo</span></code>, for both <code class="docutils literal notranslate"><span class="pre">before</span></code> and <code class="docutils literal notranslate"><span class="pre">after</span></code> events. Note that
we say “as a monitor”, not “the monitor”: we can have any number of
monitors over the same events.</p>
<p>From now on, every time we sent a message to <code class="docutils literal notranslate"><span class="pre">foo</span></code>, the <code class="docutils literal notranslate"><span class="pre">stop_watch</span></code>
monitor will print the starting and ending times for the message
execution. For instance:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- foo::bar(X).

foo &lt;-- bar(X) from user
STARTING at 12.87415 seconds
foo &lt;-- bar(1) from user
ENDING at 12.87419 seconds

X = 1
yes
</pre></div>
</div>
<p>To stop profiling the messages sent to <code class="docutils literal notranslate"><span class="pre">foo</span></code> we use the
<a class="reference internal" href="../refman/predicates/abolish_events_5.html#predicates-abolish-events-5"><span class="std std-ref">abolish_events/5</span></a> built-in predicate:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- abolish_events(_, foo, _, _, stop_watch).

yes
</pre></div>
</div>
<p>This call will abolish all events defined over the object <code class="docutils literal notranslate"><span class="pre">foo</span></code>
assigned to the <code class="docutils literal notranslate"><span class="pre">stop_watch</span></code> monitor.</p>
</section>
<section id="summary">
<h2>Summary<a class="headerlink" href="#summary" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p>An event is defined as the sending of a (public) message to an
object.</p></li>
<li><p>There are two kinds of events: <code class="docutils literal notranslate"><span class="pre">before</span></code> events, generated before a
message is processed, and <code class="docutils literal notranslate"><span class="pre">after</span></code> events, generated after the
message processing has completed successfully.</p></li>
<li><p>Any object can be declared as a monitor to any event. A monitor shall
reference the <code class="docutils literal notranslate"><span class="pre">monitoring</span></code> built-in protocol in the object opening
directive.</p></li>
<li><p>A monitor defines event handlers, the predicates
<a class="reference internal" href="../refman/methods/before_3.html#methods-before-3"><span class="std std-ref">before/3</span></a> and <a class="reference internal" href="../refman/methods/after_3.html#methods-after-3"><span class="std std-ref">after/3</span></a>, that are
automatically called by the runtime engine when a spied event occurs.</p></li>
<li><p>Three built-in predicates, <a class="reference internal" href="../refman/predicates/define_events_5.html#predicates-define-events-5"><span class="std std-ref">define_events/5</span></a>,
<a class="reference internal" href="../refman/predicates/current_event_5.html#predicates-current-event-5"><span class="std std-ref">current_event/5</span></a>, and
<a class="reference internal" href="../refman/predicates/abolish_events_5.html#predicates-abolish-events-5"><span class="std std-ref">abolish_events/5</span></a>,
enables us to define, query, and abolish both events and monitors.</p></li>
</ul>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="reflection.html" class="btn btn-neutral float-left" title="A reflective class-based system" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="../faq/index.html" class="btn btn-neutral float-right" title="FAQ" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 1998-2025, Paulo Moura.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>